home *** CD-ROM | disk | FTP | other *** search
/ Freelog 100 / FreelogNo100-NovembreDecembre2010.iso / Musique / solfege / solfege-win32-3.17.0.exe / {app} / bin / Lib / DocXMLRPCServer.py < prev    next >
Text File  |  2006-06-09  |  11KB  |  307 lines
  1. """Self documenting XML-RPC Server.
  2.  
  3. This module can be used to create XML-RPC servers that
  4. serve pydoc-style documentation in response to HTTP
  5. GET requests. This documentation is dynamically generated
  6. based on the functions and methods registered with the
  7. server.
  8.  
  9. This module is built upon the pydoc and SimpleXMLRPCServer
  10. modules.
  11. """
  12.  
  13. import pydoc
  14. import inspect
  15. import re
  16. import sys
  17.  
  18. from SimpleXMLRPCServer import (SimpleXMLRPCServer,
  19.             SimpleXMLRPCRequestHandler,
  20.             CGIXMLRPCRequestHandler,
  21.             resolve_dotted_attribute)
  22.  
  23. class ServerHTMLDoc(pydoc.HTMLDoc):
  24.     """Class used to generate pydoc HTML document for a server"""
  25.  
  26.     def markup(self, text, escape=None, funcs={}, classes={}, methods={}):
  27.         """Mark up some plain text, given a context of symbols to look for.
  28.         Each context dictionary maps object names to anchor names."""
  29.         escape = escape or self.escape
  30.         results = []
  31.         here = 0
  32.  
  33.         # XXX Note that this regular expressions does not allow for the
  34.         # hyperlinking of arbitrary strings being used as method
  35.         # names. Only methods with names consisting of word characters
  36.         # and '.'s are hyperlinked.
  37.         pattern = re.compile(r'\b((http|ftp)://\S+[\w/]|'
  38.                                 r'RFC[- ]?(\d+)|'
  39.                                 r'PEP[- ]?(\d+)|'
  40.                                 r'(self\.)?((?:\w|\.)+))\b')
  41.         while 1:
  42.             match = pattern.search(text, here)
  43.             if not match: break
  44.             start, end = match.span()
  45.             results.append(escape(text[here:start]))
  46.  
  47.             all, scheme, rfc, pep, selfdot, name = match.groups()
  48.             if scheme:
  49.                 url = escape(all).replace('"', '"')
  50.                 results.append('<a href="%s">%s</a>' % (url, url))
  51.             elif rfc:
  52.                 url = 'http://www.rfc-editor.org/rfc/rfc%d.txt' % int(rfc)
  53.                 results.append('<a href="%s">%s</a>' % (url, escape(all)))
  54.             elif pep:
  55.                 url = 'http://www.python.org/peps/pep-%04d.html' % int(pep)
  56.                 results.append('<a href="%s">%s</a>' % (url, escape(all)))
  57.             elif text[end:end+1] == '(':
  58.                 results.append(self.namelink(name, methods, funcs, classes))
  59.             elif selfdot:
  60.                 results.append('self.<strong>%s</strong>' % name)
  61.             else:
  62.                 results.append(self.namelink(name, classes))
  63.             here = end
  64.         results.append(escape(text[here:]))
  65.         return ''.join(results)
  66.  
  67.     def docroutine(self, object, name=None, mod=None,
  68.                    funcs={}, classes={}, methods={}, cl=None):
  69.         """Produce HTML documentation for a function or method object."""
  70.  
  71.         anchor = (cl and cl.__name__ or '') + '-' + name
  72.         note = ''
  73.  
  74.         title = '<a name="%s"><strong>%s</strong></a>' % (anchor, name)
  75.  
  76.         if inspect.ismethod(object):
  77.             args, varargs, varkw, defaults = inspect.getargspec(object.im_func)
  78.             # exclude the argument bound to the instance, it will be
  79.             # confusing to the non-Python user
  80.             argspec = inspect.formatargspec (
  81.                     args[1:],
  82.                     varargs,
  83.                     varkw,
  84.                     defaults,
  85.                     formatvalue=self.formatvalue
  86.                 )
  87.         elif inspect.isfunction(object):
  88.             args, varargs, varkw, defaults = inspect.getargspec(object)
  89.             argspec = inspect.formatargspec(
  90.                 args, varargs, varkw, defaults, formatvalue=self.formatvalue)
  91.         else:
  92.             argspec = '(...)'
  93.  
  94.         if isinstance(object, tuple):
  95.             argspec = object[0] or argspec
  96.             docstring = object[1] or ""
  97.         else:
  98.             docstring = pydoc.getdoc(object)
  99.  
  100.         decl = title + argspec + (note and self.grey(
  101.                '<font face="helvetica, arial">%s</font>' % note))
  102.  
  103.         doc = self.markup(
  104.             docstring, self.preformat, funcs, classes, methods)
  105.         doc = doc and '<dd><tt>%s</tt></dd>' % doc
  106.         return '<dl><dt>%s</dt>%s</dl>\n' % (decl, doc)
  107.  
  108.     def docserver(self, server_name, package_documentation, methods):
  109.         """Produce HTML documentation for an XML-RPC server."""
  110.  
  111.         fdict = {}
  112.         for key, value in methods.items():
  113.             fdict[key] = '#-' + key
  114.             fdict[value] = fdict[key]
  115.  
  116.         head = '<big><big><strong>%s</strong></big></big>' % server_name
  117.         result = self.heading(head, '#ffffff', '#7799ee')
  118.  
  119.         doc = self.markup(package_documentation, self.preformat, fdict)
  120.         doc = doc and '<tt>%s</tt>' % doc
  121.         result = result + '<p>%s</p>\n' % doc
  122.  
  123.         contents = []
  124.         method_items = methods.items()
  125.         method_items.sort()
  126.         for key, value in method_items:
  127.             contents.append(self.docroutine(value, key, funcs=fdict))
  128.         result = result + self.bigsection(
  129.             'Methods', '#ffffff', '#eeaa77', pydoc.join(contents))
  130.  
  131.         return result
  132.  
  133. class XMLRPCDocGenerator:
  134.     """Generates documentation for an XML-RPC server.
  135.  
  136.     This class is designed as mix-in and should not
  137.     be constructed directly.
  138.     """
  139.  
  140.     def __init__(self):
  141.         # setup variables used for HTML documentation
  142.         self.server_name = 'XML-RPC Server Documentation'
  143.         self.server_documentation = \
  144.             "This server exports the following methods through the XML-RPC "\
  145.             "protocol."
  146.         self.server_title = 'XML-RPC Server Documentation'
  147.  
  148.     def set_server_title(self, server_title):
  149.         """Set the HTML title of the generated server documentation"""
  150.  
  151.         self.server_title = server_title
  152.  
  153.     def set_server_name(self, server_name):
  154.         """Set the name of the generated HTML server documentation"""
  155.  
  156.         self.server_name = server_name
  157.  
  158.     def set_server_documentation(self, server_documentation):
  159.         """Set the documentation string for the entire server."""
  160.  
  161.         self.server_documentation = server_documentation
  162.  
  163.     def generate_html_documentation(self):
  164.         """generate_html_documentation() => html documentation for the server
  165.  
  166.         Generates HTML documentation for the server using introspection for
  167.         installed functions and instances that do not implement the
  168.         _dispatch method. Alternatively, instances can choose to implement
  169.         the _get_method_argstring(method_name) method to provide the
  170.         argument string used in the documentation and the
  171.         _methodHelp(method_name) method to provide the help text used
  172.         in the documentation."""
  173.  
  174.         methods = {}
  175.  
  176.         for method_name in self.system_listMethods():
  177.             if self.funcs.has_key(method_name):
  178.                 method = self.funcs[method_name]
  179.             elif self.instance is not None:
  180.                 method_info = [None, None] # argspec, documentation
  181.                 if hasattr(self.instance, '_get_method_argstring'):
  182.                     method_info[0] = self.instance._get_method_argstring(method_name)
  183.                 if hasattr(self.instance, '_methodHelp'):
  184.                     method_info[1] = self.instance._methodHelp(method_name)
  185.  
  186.                 method_info = tuple(method_info)
  187.                 if method_info != (None, None):
  188.                     method = method_info
  189.                 elif not hasattr(self.instance, '_dispatch'):
  190.                     try:
  191.                         method = resolve_dotted_attribute(
  192.                                     self.instance,
  193.                                     method_name
  194.                                     )
  195.                     except AttributeError:
  196.                         method = method_info
  197.                 else:
  198.                     method = method_info
  199.             else:
  200.                 assert 0, "Could not find method in self.functions and no "\
  201.                           "instance installed"
  202.  
  203.             methods[method_name] = method
  204.  
  205.         documenter = ServerHTMLDoc()
  206.         documentation = documenter.docserver(
  207.                                 self.server_name,
  208.                                 self.server_documentation,
  209.                                 methods
  210.                             )
  211.  
  212.         return documenter.page(self.server_title, documentation)
  213.  
  214. class DocXMLRPCRequestHandler(SimpleXMLRPCRequestHandler):
  215.     """XML-RPC and documentation request handler class.
  216.  
  217.     Handles all HTTP POST requests and attempts to decode them as
  218.     XML-RPC requests.
  219.  
  220.     Handles all HTTP GET requests and interprets them as requests
  221.     for documentation.
  222.     """
  223.  
  224.     def do_GET(self):
  225.         """Handles the HTTP GET request.
  226.  
  227.         Interpret all HTTP GET requests as requests for server
  228.         documentation.
  229.         """
  230.         # Check that the path is legal
  231.         if not self.is_rpc_path_valid():
  232.             self.report_404()
  233.             return
  234.  
  235.         response = self.server.generate_html_documentation()
  236.         self.send_response(200)
  237.         self.send_header("Content-type", "text/html")
  238.         self.send_header("Content-length", str(len(response)))
  239.         self.end_headers()
  240.         self.wfile.write(response)
  241.  
  242.         # shut down the connection
  243.         self.wfile.flush()
  244.         self.connection.shutdown(1)
  245.  
  246. class DocXMLRPCServer(  SimpleXMLRPCServer,
  247.                         XMLRPCDocGenerator):
  248.     """XML-RPC and HTML documentation server.
  249.  
  250.     Adds the ability to serve server documentation to the capabilities
  251.     of SimpleXMLRPCServer.
  252.     """
  253.  
  254.     def __init__(self, addr, requestHandler=DocXMLRPCRequestHandler,
  255.                  logRequests=1):
  256.         SimpleXMLRPCServer.__init__(self, addr, requestHandler, logRequests)
  257.         XMLRPCDocGenerator.__init__(self)
  258.  
  259. class DocCGIXMLRPCRequestHandler(   CGIXMLRPCRequestHandler,
  260.                                     XMLRPCDocGenerator):
  261.     """Handler for XML-RPC data and documentation requests passed through
  262.     CGI"""
  263.  
  264.     def handle_get(self):
  265.         """Handles the HTTP GET request.
  266.  
  267.         Interpret all HTTP GET requests as requests for server
  268.         documentation.
  269.         """
  270.  
  271.         response = self.generate_html_documentation()
  272.  
  273.         print 'Content-Type: text/html'
  274.         print 'Content-Length: %d' % len(response)
  275.         print
  276.         sys.stdout.write(response)
  277.  
  278.     def __init__(self):
  279.         CGIXMLRPCRequestHandler.__init__(self)
  280.         XMLRPCDocGenerator.__init__(self)
  281.  
  282. if __name__ == '__main__':
  283.     def deg_to_rad(deg):
  284.         """deg_to_rad(90) => 1.5707963267948966
  285.  
  286.         Converts an angle in degrees to an angle in radians"""
  287.         import math
  288.         return deg * math.pi / 180
  289.  
  290.     server = DocXMLRPCServer(("localhost", 8000))
  291.  
  292.     server.set_server_title("Math Server")
  293.     server.set_server_name("Math XML-RPC Server")
  294.     server.set_server_documentation("""This server supports various mathematical functions.
  295.  
  296. You can use it from Python as follows:
  297.  
  298. >>> from xmlrpclib import ServerProxy
  299. >>> s = ServerProxy("http://localhost:8000")
  300. >>> s.deg_to_rad(90.0)
  301. 1.5707963267948966""")
  302.  
  303.     server.register_function(deg_to_rad)
  304.     server.register_introspection_functions()
  305.  
  306.     server.serve_forever()
  307.